home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 25
/
Cream of the Crop 25.iso
/
comm
/
yep16.zip
/
YEP.DOC
< prev
next >
Wrap
Text File
|
1997-04-09
|
62KB
|
1,313 lines
Y E P
Yarn Editor Pre/Post Processor
Y E P
Version 1.6
Contents:
~~~~~~~~~
-1- ------------------------------- Introduction to Yep
-2- ------------------------------- Installation of Yep
(------------- Edit Yarn CONFIG
(----------------- Edit Yep.cfg
(--------------Yep but Not Yarn
-3- ------------------------------- Tags & Substitution
(-------------- {RNDL:filename} (random line)
(-------------- {RNDF:filename} (random file)
(-------------- {IMPF:filename} (import file)
(---- {EXEC:filename arguments} (execute program)
(------------ {IMPL:#:filename} (import line)
(- {IMPLS:"string"::"filename"} (line string)
(---- {IMPLR:L#:S#:C#:filename} (line range)
(----------------- Subsitutions
-4- ------------------------------- Yep Operation Notes
(---------------- . Translation
(---------------- Mailing Lists
(------------------ SIG Example
-5- ------------------------------- Of Conditional Tags
(-------------- {IFTO:any text}
(------------ {IFSUBJ:any text}
(------------ {IFDATE:any text}
(-------------- {IFNG:any text}
(-------------- {IFXN:any text}
(-------------- {IFCC:any text}
(------------- {IFBCC:any text}
(-------------- {IFRT:any text}
(---------- {IFFLAG:true/false}
(--------- {SETFLAG:true/false}
-6- ------------------------------- Capturing Your URLs
-7- ------------------------------- UUencoding and Yep!
(---------------{UUEN:filename}
-8- ------------------------------- Of Specialized Tags
(--------------------- {EXPD:#} (expiry date)
(---------------- {DATE:string} (date/time/more!)
(---------------------- {POM:#} (phase of moon)
(----------------- {YPDEC:code} (Yep decrypt)
(------------------- {RNDN:#:#} (random number)
(---------------- {RNDC:string} (random character)
(---------------- {HEADER:name} (header values)
(----------- Special Precedence
-9- ------------------------------- Block Process & PGP
-10- ------------------------------- Anonymous Remailers
-11- ------------------------------- Of Finding Problems
*12* ------------------------------- History of Revision
-13- ------------------------------- Who, what and where
-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-1-
Introduction to Yep:
-------------------
Yep is an "editor shell" for use specifically with the Yarn off-line
newsreader (OS/2 version). Yep will also work with other mail/news
readers which call external text editors.
Yep provides the following functionality:
- Start your editor with the first line number past the message
header, or quotes in a reply, (if your editor supports it)
- Append your own lines to message headers.
- Embedded macro tags at any point can:
- import random lines of text (suitable for taglines,
SIG lines, random header messages, etc)
- import files automatically into messages.
- import random files (ie. useful for random SIGs)
- execute programs (useful to create macros which
automatically import the text output of
a program)
- conditionally do/print things based on current
newsgroup, to, date, or subject field.
(for example, have custom headers or SIG
files for particular newsgroups)
- User defined substitution code table to create "macros" from
the above tags, create custom abbreviations, or correct common
spelling errors.
- Optionally strip unused header entries when starting editor
- Automatic URL capturing / logging / converting
- Lightning fast built in UUencoder for file importing
- Block Processing for filters/PGP encryption, etc
- Many, many, many more weird and wonderful things, far too
numerous to describe here. Read on!
Yep is extremely configurable. The author likes to think of it as a
program that can make every email an adventure! (-: It can be utilized
in a simple manner for basic functions (like setting start up cursor
positions), or in mind bogglingly complex customised craziness.
It should be mentioned that there is already an excellent, and far
more comprehensive "editor shell" for Yarn which is called "Yes". My
reason for creating my own shell was mainly because there is no OS/2
version of Yes (at this time); and also creating my own shell I can
tailor it to my specific (and possibly insane) desires. I have no idea if
anyone else may find it useful to them, but here it is.
And after all, you could set yourself up to use both Yep and Yes at the
same time, if you really want to. (-:
-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-2-
Installation of Yep:
-------------------
It doesn't matter what directory you place YEP.EXE in, just as long
as the YEP.CFG is in the same directory.
1. Edit your Yarn CONFIG file.
Edit the line which begins "editor=". This line should now read:
editor=<path>\YEP.EXE
where <path> is the path to wherever you placed the YEP.EXE.
Note: Yep should have no parameters on that line. You will
define the command line for you editor in the YEP.CFG file.
2. Edit your YEP.CFG file.
There are comments in this file (all lines beginning with a
semi-colon (;) are comment lines), so not many details will be
given in this document. Refer to the Yep.Cfg for instruction.
You may use multiple copies of YEP for different users of yarn
on your system. The YEP will always look for a CFG file that has
the same root name as itself. Therefore if you made another
copy of Yep and called it YEP2.EXE you would then create a
YEP2.CFG file, which could have it's own set up.
In the Yep.Cfg if you specify the full path (and EXE extension)
of your editor it will be called directly and speed up loading
a bit. Otherwise it is called though the command shell and your
path is searched.
That's all there is to basic installation. How you use and customize
Yep is up to you.
Yep But Not Yarn
----------------
Yep will work with some other OS/2 news/mail readers which meet
the following criteria:
- uses an external text editor
- sends message headers to the editor
Yep may have to be configured to recognise the filename of
messages used with your news reader. See the line beginning
Process= in the Yep.cfg for details. Yep is set up by default
to recognise Yarn, MR2ice (see the MR2ice.doc included).
-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-3-
Tags & Substitution:
-------------------
A major concept of Yep is that of it's "macro" tags. Each message is
scanned for substitutions and tags before the editor starts, as well
as after the editor exits. There are at this time only a few tags
implemented (but many things can be done with them).
The basic syntax for tags are:
{TAG:arguments}
TAG is the name of the tag to be used, followed by a colon, followed
immediately by information that the tag is to work with. Tags are
not case sensitive-- they can be upper or lower or mixed case.
Tags and substitutions are scanned sequentially on each line and
therefore nesting (tags within tags) will not work. However all
substitutions are done before any tags are interpreted, therefore
you can put substitution codes inside tags (i'm not sure what for).
Yep attempts to "translate" or "filter" all text that goes though
it. It can get somewhat complex, but you can also include tags in
imported files, and they will be honoured.
{RNDL:filename}
This tag will import a random line from the text file
specified. The file can be of any length. Blank lines and
lines beginning with a semi-colon (;) in the file will be
ignored.
This tag is useful for creating random "taglines" in your sig,
or a random line in a header. It may have many other uses as
well-- but that is up to you, and your imagination.
For example, if in your YEP.CFG you had a header line like
this:
X-Funny-Line: {RNDL:funny.txt}
In the above example the "X-Funny-Line:" header would be
included in your message and a random line from a text file
called "funny.txt" would follow it.
{RNDF:filename}
This tag inserts a random file. The "filename" specified will
be considered a "root" or "base" filename (ie. the filename
WITHOUT any extension). The directory containing the filename
root will be scanned looking for files with that name having
numbered extensions .1, .2, .3, and so on. The extension
numbers must be sequential, with no gaps. A random file will
be picked and inserted.
{IMPF:filename}
Very simply imports the "filename" file into your message.
It could be useful for inserting external files into a SIG,
or other places. For example, some people like to include
their PGP key in their sig. You could do that by including
{ImpF:c:\pgp\mykey.asc} in your SIG file (note: Yep does not
append a SIG file itself, but interprets the SIG file that
Yarn appends to each message). In this way if you upgrade
PGP to a new version and export a new key to the filename
noted above, your sig will always automatically have the
latest extracted version of your key.
{EXEC:filename arguments}
This causes your message to stop and execute a file. The
idea here is that you might have a file which output some
text you would like to insert into the message: perhaps
random quotations, or up to the second system statistics.
You can execute the file with this tag and redirect the
output to a temporary file, and then use the IMPF tag to
read in the newly created temporary file.
See the Yep.Cfg file for a few examples of this.
As with the text editor configuration, if you specify
a full path (with EXE extension) for your filename to
EXEC then the program will be called directly, which
speeds things up. Otherwise the file is run though the
command processor and path is searched.
Note: if you are using the EXEC tag to capture output
using standard I/O redirection, do NOT include the EXE
on the path/filename, as the program must be executed
indirectly through your command processor in order to do
standard output redirection. (See below in the "substitutions"
section for more details).
{IMPL:#:filename}
Perhaps there is a text file from which is only wanted a
single specific line of text (for example: to grab a line
of information from the output of a text file generated
by some other program}. With the ImpL tag you specify the
line number you wish to read where the # is (do not include
a # symbol), followed by a colon (:), and the filename.
As an example: perhaps in your mail headers you would like
to display to the world how long your computer has been
running. There is a nice utility called "Go" by Carston Wimmer
(ftp://hobbes.nmsu.edu/os2/textutil/go_15.zip) which will
display OS/2's "up time" (and will do much more). However
the output of Go also includes title/copyright line of text
which you don't want to import: all you want is the "up time"
reported on line 3 of Go's report.
The output of "go -ut" might look like this:
GO! v1.5 - (c) 1993-95 by Carsten Wimmer <cawim@train.oche.de>
Uptime: 1d 23h 56m 59s 364ms
Therefore you might include in your yep.cfg a header
definition which would look like this:
X-OS2-{exec:go -ut >utmp}{impL:3:utmp}
The first tag in the above example executes the "Go" utility
with the "-ut" switch and redirects the output to a work file
called "utmp". The next tag then directs Yep to import line
three, and only line three, of the work file that was created.
Note also that the output of Go, with the -ut switch, includes
a header-like "Uptime:", so in our example the fine output of
your header would look like this:
X-OS2-Uptime: 1d 23h 56m 59s 364ms
{IMPLS:"string"::"filename"}
Import the first line from a text file with begins with the
string specified. For example, lets use the "GO" program
again. Say you wanted to report in your message (God, only
knows why) the current number of processes and threads
active. When you EXEC "GO" it gives a list of all your
processes running, and a summary at the bottom. We can not
use IMPL (import line) because the summary is going to be
on a different line depending how many processes were in
the list above it. The summary line given by "GO" looks like
this:
There are 11 Processes with 66 Threads.
Using the IMPLS tag we can search for the first string in
our temporary capture file (see EXEC procedure) beginning
with "There are". The tags would then perhaps look like this:
{EXEC:go >utmp}{ImpLS:"There are"::"utmp"}
{IMPLR:L#:S#:C#:filename}
This variation works the same as {IMPL:#:filename}
(import line), but with the added control of being able to
only import a portion of that line. Three numbers must be
specified: L# is the line number to be imported; S# is the
starting column of the line to import; and C# is the count
number of characters to import from that starting position.
For example, say there was a program you ran with an EXEC
tag which outputs...
After giving this much thought i have realized that I can
dream up no practical application for this tag! You are
on your own! If you ever need to import just a portion
of a certain line (for some task i can not even imagine),
here is the tag to do it with! ImpLR stands, only slightly
confusingly, for "import line range". That's that.
Substitutions:
-------------
It would be rather awkward if you had to type in then entire tag,
with filenames, and whatever other data that needs to be given,
therefore you can define your own tags by using a substitution table.
In the Yep.Cfg you may define (currently) up to 100 substitutions.
For example, say you wanted a quick way to import your PGP public
key into a message when someone asks for it. Rather than typing:
{impf:c:\pgp\my.key}, you could set up a substitution in the Yep.Cfg
something like this (refer to Yep.Cfg for details on the format):
"{pk}"::"{impf:c:\pgp\my.key}"
Now whenever you want to insert your PGP public key you would only
need to quickly type {pk} in your message and it would be inserted.
This is just an example, you could make it whatever you wanted.
For another example, silly as it may be, say you had a fetish about
how much disk drive space you have free at any given moment, and you
are obsessed with telling everyone in every message how much drive
space is available that very second. You could define a substitution
something like so (assuming you have a utility called "free" which
reports current free disk space):
"{ds}"::"{exec:free >tmp}{impf:tmp}"
In this way the "free" command is executed and its output is
redirected to a temporary text file which is then imported into
your message. (Note: if you are going to use ">" redirection
to send output to a file, Yep needs to go through your OS command
interpreter shell-- in this case do not include a full path to
your program, as directly calls will not have redirected output.)
-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-4-
Yep Operation Notes:
-------------------
Dot Translation:
===============
When Yep runs you will see it announce itself, and then a
series of coloured dots. (This behaviour can be turned off in
the YEP.CFG if undesirable). Each dot tells which operation
Yep has just completed during it's scanning and filtering
activities. In this way you can tell how long certain
operations take, as well as possibly debug certain problems;
not to mention it's a form of cheep entertainment if you are
tired of watching television.
Yep begins by announcing itself as "Yep...". This just tells you
the shell has started. After that dots follow:
LIGHTBLUE - an user defined header line has been inserted.
LIGHTGREEN - a substitution action has taken place.
GREEN - A random line (RNDL) has been fetched (BLUE if it fails).
BROWN - Yep has successfully imported a text file (IMPF/IMPR).
YELLOW - Yep has attempted to import a text file but failed.
GRAY - this is a potentially important dot: it indicates that
yep is about to execute (EXEC) a program. A DARK grey dot
means it is attempting to execute the program directly, a
LIGHT gray dot means it is executing through your OS shell.
This dot also shows up immediately before the Editor is
called, so the user can see how quickly Yep pre-processes
the file, and calls the editor (depending on system speed).
PINK - YPDec has decrypted a code, or a random number generated.
BLUE - is a general error, and an error usually is given.
After you finish editing your message Yep scans the message for
any new processing instructions. The above colours apply. When
it is finished it signs off with "...Yep" and returns you to Yarn.
Mailing Lists:
=============
Rather a cheap hack, but one could, if one wanted, create a
file with a comma separated list of addresses. Then create a
substitution code which loads that file, something like:
"{list1}"::"{IMPF:c:\yarn\MailLst1}"
With this set up you only need to type {list1} in the Bcc: or
Cc: field of your message and the list of addresses will be
imported/substituted, and therefore mailed to everyone.
Alternately you can just define a substitution that has your
"mailing list" in it, and avoid having to import a file.
"{L2}"::"someone@somewhere.edu,another@addr.com"
Note: addresses are separated by commas. In the above
example if you entered {l2} in the To:, Cc: or Bcc: field
of a message then it will be substituted with the comma
delimited list.
SIG-gy Tricks:
=============
Note: Yep does not append a SIG file, but relies on Yarn
to append the SIG file. Yep however interprets whatever
it finds in Yarn's SIG file allowing for many tricks.
Using various substitution codes you can do quite flexible
things with your SIG file. Not only can you have complete
randomly chosen SIG files, and link external files, but
individual elements inside your SIG can be randomized via
the RNDL tag. For example, my current SIG file looks like
this (this is just one small example of the possibilities):
{rndl:c:\osu\yarn\sig1top.lst}
Tim Middleton {rndl:c:\osu\yarn\sig1luv.lst} as544@torfree.net
{rndl:c:\osu\yarn\sig1red.lst}
{rndl:c:\osu\yarn\sig1end.lst}
What it does is gets a random top element from a list,
then prints my name, inserts another random element from
a different list, and then my email address. Furthermore,
it then inserts another randomly chosen line, and finally
a randomly chosen bottom element. The finally output
might look like this (call me crazy, I love randomness!):
.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.+.
Tim Middleton -with love and tomato sandwiches- as544@torfree.net
-=-= brace yourself and read The Idiot by Fyodor Dostoyevsky =-=-
~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~`'~
-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-5-
Of Conditional Tags:
-------------------
The idea here is to give the user even more automated
customization of their messages. For example, with conditional
tags you can implement different SIGs based on the newsgroup
being posted to. Or custom header lines based on who the
message is To. This seemed like a good idea to me when I
started working on it. Now I'm not sure if it's worth the
trouble. You can safely ignore it if it doesn't sound useful
to you.
The way these tags work is that if the condition in them is
met (ie. if it is true) then the rest of the line will be
filtered through, otherwise the rest of the line will be
discarded. If the conditional tag begins in column one and
returns false then the entire line will be skipped.
The new tags are:
{IFTO:any text}
If the text specified in the "any text" is found in the To:
field of the header then the rest of the line is processed.
{IFSUBJ:any text}
Same as above, only the Subject: field is checked.
{IFDATE:any text}
Same as above, only the Date: field is checked. Perhaps you
want special text automatically inserted into your messages
on Fridays. I have no idea why!
{IFNG:any text}
Same as above, only the Newsgroups: field is checked. This
one is possibly the most potentially useful; allowing custom
headers or footer messages to be inserted when posting in
certain newsgroups. Maybe. (For an example of how to use
specific SIGs on individual newsgroups see IFFLAG below).
{IFXN:any text}
Same as IFNG except this one checks the X-Newsgroups: field.
{IFCC:any text}
Same as IFTO except this one checks the Cc: field.
{IFBCC:any text}
Same as IFTO except this one checks the Bcc: field.
{IFRT:any text}
Same as IFTO except this one checks the Reply-To: field.
{IFFLAG:true/false}
This tag needs a little more explanation. Consider the following
example Yarn SIG file (explanation to follow):
{IfNG:comp.os2}{ImpF:c:\yarn\os2.sig}
{IfNG:comp.windows}{ImpF:c:\yarn\wind.sig}
{IfNG:alt.books}{ImpF:c:\yarn\book.sig}
{IfFlag:false}{IfTO:peri strange}{ImpF:c:\yarn\peri.sig}
{ifFlag:false}{ImpF:c:\yarn\default.sig}
As you have hopefully noticed, this example sig tests to see
if the user is posting in the various newsgroups: comp.os.*,
comp.windows.*, and alt.books.*; and if so then imports the
appropriate SIG file you have created.
There is a global "FLAG" which begins always set to "false".
Whenever a conditional tag returns a "true" status the global
flag is set to "TRUE". Therefore in line four of the above SIG
example, you are first testing to see if any of the above
conditions have already been met. If they have then the rest
of line four is skipped. If a sig has not yet been imported (so
the global flag is still False) then it is checked to see if
the message is to your good friend "Peri Strange"-- who gets
his own sig to amuse him. Finally on the last line it is checked
again if no other conditions returned true this line will use the
"random file" tag to import a default SIG file with the name as
specified. (see the {IMPF:filename} tag in section 3).
Lines beginning with an "if" tag as the first thing on the line
will not output anything (ie. will not leave a blank line) if
any conditions being tested fail before any text is printed.
{SETFLAG:true/false}
There might be some circumstance, however unlikely, where you
need to set or reset the global flag. An example would be if you
have custom headers that test for certain dates or newsgroups,
and then at the bottom of the message have a SIG that does more
tests. To reset the global flag to FALSE simply put the following
tag on a line starting in column one:
{SetFlag:false}
The line will be skipped in the message output, but the flag will
be set to False at that point.
-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-6-
Capturing Your URLs
-------------------
This feature is disabled by default. To enable it uncomment the
UrlLog = "c:\path\filename" line in the yep.cfg, and specify the
path/filename you want to use.
Once enabled, when Yep is scanning any message it will attempt
to detect all URLs (Uniform Resource Locator, i.e. http://) and
make a record of them to the log file specified. Along with the
URL address it will record the date of the message, who it is
from (if available), and/or the newsgroup(s) it was posted to.
There is a new section in the yep.cfg labeled beginning with
[URL EXLUCLUSIONS] (see the yep.cfg comments for more info).
You can specify up to 25 URLs which commonly occur in your
reply messages, so Yep will not keep capturing them each time.
For example, you might want to put any URL which you have in
your SIG into this list to keep it form being captured over
and over and over and over and over again.
If you want to capture the URLs in a message you are reading
you will have to press Shift-R, as if you were going to reply.
The URLs will be captured, and then exit your editor and press
Escape, or C, to cancel the reply. A bit awkward, but it's the
only way Yep gets an opertunity to scan the message.
There are several tools provided to help manage your captured
URLs. They are all REXX scripts with filenames beginning with
YepU. Please see the YepU.DOC for details on each of them.
Briefly, they include tools which will count, trim, filter and
eliminate duplicates, as well as convert to HTML or Web Explorer
URL Objects on your OS/2 WPS desktop.
There is no special format to the Yep URL Capture Log. It is
a plain text file which you are free to edit or modify as you
wish. The entries for each record can be anything, and in any
order. The only rules are that there must be at least one blank
line between each URL record (and no blank lines in a record),
and at least one blank line at the bottom of the Log File.
In your YEP.CFG file there is a section where you can specify
URLs to ignore -- so they won't be logged over and over again.
This is useful especially if you have your web page(s) listed
in your SIG! See the [URL EXLUSIONS] section of YEP.CFG.
-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-7-
UUencoding with Yep!
--------------------
Have you ever reflected on the irony of how Yarn provides
excellent built in support to attach a file to your message
via MIME encoding. Yet to decode a MIME message you need
an external program which can be finicky to set up. Yarn,
on the other hand, has a very quick and easy built in method
to extract and decode a UUencoded file found within a message
at the touch of a button... yet Yarn has no way built in
to UUencode a message! With one method you get easy encoding,
but not decoding; with the other you get easy decoding, but
not encoding!
Yep provides a very quick and easy way to UUencode a file
into your messages. When you are at the point in your message
where you want to UUencode a file and insert it simply type
the following code:
{uuen:filename}
The "filename" portion of the code would be, of course, the
filename (and path if needed) of the file you want to insert.
As soon as you exit your text editor Yep will notice the
UUencode command tag and load the file, and using internal
UUencoding routines, inject it into your message at that point.
No fuss, no muss. Quick and easy.
You will see a brown capitol "U" while Yep is importing and
UUencoding the file, just to let you know it found the
instruction and is attempting to preform it.
-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-8-
Of Specialized Tags
-------------------
There were a few external programs being used which I decided
to bloat Yep up a bit by making internal. The small external
programs are still included in the package for backward
compatability and flexibility; but if you use any of them
it will be much faster to take advantage of the new internal
routines. They are as follows:
{EXPD:#}
This tag will create a usenet timestamp # number of days
in the future. This is useful for creating "Expires:" headers
on your messages, if you so desire. An Expires: header, if you
are not aware of them, specifies an expirey date at which
time your message should be removed from news servers. There
is no guarentee that they will be on that day, or before that
date, but it gives you a chance at some control, at least.
There are two reasons you may want to use this tag. The first
reason is that perhaps you feel uncomfortable that there are
searchable databases of news messages going back YEARS out
there: anyone stalking you could track your usenet movements!
I don't know if DejaNews and others will honour the Expires
header, but they might. The other possibility is if you
want distant future expiry date for your messages to make
them last (perhaps annoyingly) long on news servers. I won't
go into further details about how news servers expires messages.
To create an Expires header in your messages you need to
create a custom header that might look like this:
Expires: {ExpD:7}
With the above custom header all of your messages will be
set to expire in one week (seven days). If you want to set up
expiry dates for only certain newsgroups then you may want
to use the conditional {ifNG:string} tag. For example, if you
want all silly questions in the comp.* hierarchy to expire
after five days you could make a header like this:
{ifng:comp.}Expires: {ExpD:5}
Note: the hard coded upper limit for your number of days
possible until expiry is 1000.
{DATE:string}
(Note: This is a "special precedence" tag, see the section
below on special precedences for more details)
This is an implementation of the "DateTime" program. The "string"
you give to this tag may contain a wide array of special substitution
codes which allow you astonishing flexibility to output the current
date and/or time any way you please, wherever you please (and also
some other strange things, like the percentage of the year or day
that has past so far, and other things. For example, the simplest
way to print the entire current date and time in long form would
be:
{Date:It is now @t on @d.}
This would print:
It is now 4:21 am on Monday, February 16th, 1996.
With different substitutions any format is possible. The complete
table of possible date/time substitutions follows:
@d - the full date (Monday, February 16, 1996)
@t - 12 time of day (4:21 am)
unit no lead ld zero ld spce Nth
---- ------- ------- ------- ----
month number - @m1 @m2 @m3 @m4
day of month - @d1 @d2 @d3 @d4
12 hour - @h1 @h2 @h3 @h4
24 hour - @H1 @H2 @H3 @H4
minute - @n1 @n2 @n3 @n4
second - @s1 @s2 @s3 @s4
hundredths - @u1 @u2 @u3 @u4
day of year - @a1 @a2 @a3 @a4
@y - year @y1 - 2 digit year
@i - am/pm @i1 - AM/PM @i2 - Am/Pm
@i3 - morning/afternoon/evening
@M - month name @M1 - 3 letters @M2 - 2 letters
@W - weekday name @W1 - 3 letters @W2 - 2 letters
@W3 - num @W4 - Nth
@p1 - % day gone @p2 - % year gone
@t1 - tenth/Second
{POM:#}
The ever popular *new* Phase of the Moon program (POM.EXE) is
now internal to yep. You may use this tag in headers or wherever.
The # should be a value between 0 and 12, and represents how many
decimal places of the moon's current phase should be shown.
For example {PoM:4} would yield:
The Moon is a Waxing Crescent (49.0512% of Full).
{YPDEC:code}
(Note: This is a "special precedence" tag, see the section
below on special precedences for more details)
This tag decrypts the given YP-Encrypted code and inserts it
into your message. The YPEnc program to generate the encrypted
codes is included with the Yep package, and has it's own little
documentation file which you should refer to if you think you
may use this feature. In a nutshell it is to make the storage
of passwords (such as for use in tags with anonymous remailers)
slightly safer (but not much more safer) from prying eyes. You
would use the YPEnc program to generate the code and then save
the code with this tag in your Yep.Cfg. See the YPEnc.Doc.
{RNDN:#:#}
This tag replaces itself with a random number in the given
range. For example {RndN:2:6} will be substituted with a
number between 2 and 6 (inclusive). Although I'm sure you
may just want to generate random numbers in your messages
for absolutely no reason except to admire the dazzling
creative beauty of them, there are also some possible
practical applications. This is a "special precedence" tag
(see the section below on special precedences for more details).
{RNDC:string}
This tag replaces itself with a random character out of the
given string. For example {RndC:aeiou} will be substituted
one of the five vowels randomly. Who knows what you might
use this for. I know what I use it for. (-:
{Header:name}
This tag prints out the current value of the 'named' header.
The headers supported by this function are: To, From, Subject,
Date, Newsgroups, X-Newsgroups, References, Reply-To, Sender.
For example {header:subject} would be replaced by the current
subject line. {header:newsgroups} would be replaced by the
value of the "newsgroups:" header (if it exists). And so on.
Special Precedence
------------------
A few of the tags above are given special precedence when
a line of your message is scanned. What this means is that
those special tags will be processed first, before any other
tags.
Yep is not recursive when it scans lines. What this means
is that normally you can't include Yep tags inside other
yep tags-- the inner tags will not be processed.
However a few tags have been given the special ability to
be used inside other tags. Namely: RNDN, RNDC, DATE,
and YPDEC.
Say, for example, you want to use a different SIG file
for each day of the week. In your main SIG file you could
put this tag:
{ImpF:{Date:@W1}.sig}
The DATE tag inside the IMPF (import file) tag will be
processed first, and replaced with the @W1 date code
(see the DATE tag for more details on date codes), which
is the first three letters of the day of the week. So
in the above example, on Monday the import tag would
become {ImpF:Mon.sig}, on Tuesday it would then be
{ImpF:Tue.sig}, and so on. You could also use other
Date or Time codes to do other tricks like this.
You could use the RNDN (random number) or RNDC (random
character) tag to import random filenames which contain
a range of numbers. Or you could import a random line from
a file within a certain range of line numbers.
YPDEC could be used to hide a filename in your sig,
so it is not readable. I have no idea why you might
want to do it-- but you could if you wanted to!
-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-9-
Block Processing & PGP, and More
--------------------------------
Block processing is a procedure you can set up where you create
your own tags that will identify blocks of text in a message.
When you exit your text editor Yep will search for any "Blocks"
enclosed by these tags and run a user defined process on them.
The most common possible usage for this technique is for
encrypting (ie. PGP, or another text encryption program)
portions of your message. Other more whimsical uses can be left
to your imagination.
To set up block processing with Yep you need to edit the
YEP.CFG. Specifically you define block process in the section
labeled: [BLOCK PROCESSING DEFINITIONS]. There can be up to 15
blocks defined.
For example to set up a block processing tag to run PGP one might
use the following definition:
"{pgp}"::"pgp -seat *i -o *o *p "
This is more simple than it looks. Basically there are two
sections to the line (the structure is the same as the
"substitutions" section of the CFG). The first defines the tag,
which in this case is {pgp}. This will mean that with this
definition enabled whenever Yep is post-processing your message
and sees the {PGP} (case doesn't matter) tag in the first column
it will then process the rest of that block using the command
given in the second half of the definition above (which will be
explained in detail below).
The command that is executed on the block must contain at least
two substitution codes: *i and *o. These will be replaced by yep
with the "input" and "output" filenames to be used.
The third, optional substitution code you may use in your block
command line is *p. *P will be replaced by any "parameters" you
want to pass to your text processing program (please, keep
reading for further explanation of how this works).
So a detailed breakdown of the "pgp -seat *i *p -o *o" command
above becomes more clear. The block will run the program "PGP"
with command line options "-seat" (which tells PGP to sign and
encrypt a text file with ascii output). The filename will be
given to pgp in place of the *i, and the output of pgp will go
to *o using pgp's "-o" switch. the *p in the line will be any
additional parameters. you can use this to specify who you want
to encrypt the message to right in your block command.
So, how this works in the message you are writing is as follows.
Let us assume there is a block of text you want to encrypt in
your message you are writing to your friend George, you might
write your message like this:
Dear Peri, the weather here in Tibet is lovely.
A llama spat in my eye yesterday (i mean the animal,
not a buddhist monk, this time). And oh yes, by the
way the secret word of the tetragrammaton is:
{Pgp peri}
well, i'll tell you when i get back. I fear the
U.S. government may have paid off Zimmerman to
get a back door put into PGP!
{TheEnd}
Wish you were here.
Your Pal, Tim.
So now you can see, the portion of text between the {pgp} tag
and the {theend} tag (case does not matter), will be sent to the
PGP program as you defined it. It will be encrypted.
Note, all blocks terminate with the tag {TheEnd}, or at the end
of the message. If you want the whole remaining portion of the
message encrypted you do not need to include {theEND}.
Note also that i did not simply use the tag: {Pgp}. In this
example was used {Pgp Peri}. All text after the block tag, but
before the closing of the tag, is considered "parameters". These
are the mysterious parameters that will be sent to the program
through the *p substitution in the block command definition. So
in this case "peri" will be sent. In this case it is convenient
to send the ID of the person you want to encrypt the file to
that way, instead of being prompted for it by PGP if it is not
included. The benefit of doing it this way is that you can
encrypt a message to multiple recipients this way. For example
if i wanted to encrypt that portion of the text to Peri, Joe,
and myself, I could have called the block as: [pgp peri tim].
*TIP* Another good hint for using PGP blocks is to define the
command like so: "pgp -seat *i -o *o tim *p". Notice I put my
own name (a PGP ID really) in there. This will make every
message I encrypt also be encrypted to myself (which means I
will be able to decrypt my own encrypted messages if I should
need to-- believe me, it has come in handy before!)
Hopefully the above information gives you a good basic
understanding of how the block processing works, and how to set
it up. Following will be a few more details which are not
necessary to know-- so if you are confused already you may want
to read the above section over again, and skip the below section
altogether.
Details About Brackets or Tag Enclosures:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Blocks do not have to use square brackets to enclose them, you
can use anything you want. You could have defined the pgp block
as "[pgp]". But the essential thing to know about this
technicality is that whatever characters you use to enclose your
block command you must use the same characters to terminate your
block. What i mean is that if you defined pgp with curly braces
then to terminate the block in your message you also must use
curly braces around "TheEnd", like so: [TheEnd].
Blocks May be Nested:
~~~~~~~~~~~~~~~~~~~~
Blocks can be nested inside blocks. I don't think I want to
explain that except to say that it is allowable. (-: A possible
use would be if you are sending a PGP encrypted message though
the alpha.c2.org anonymous remailer. The remailer requires your
message be encrypted to it, but also you want the message it
sends inside that encrypted message to be encrypted. You
following what I mean? You could have a message something like
this... wait! Another thing about the alpha.c2.org remailer is
that it does NOT want you to "sign" your encryption with PGP. So
with Yep block definitions you could define two different PGP
encryption tags which use different PGP command line options.
For example, in addition to the definition shown above you might
also do:
"[pgpns]"::"pgp -eat *i -o *o *p "
Notice the "s" option is missing from the command line. So in
this case "pgpNS" might stand for PGP No Signing. ANd so you
might encrypt your message like this:
[pgpns alpha]
header: your alpha-style required headers
[pgp your_friend]
Dear my_friend, i'm not sure if this is exactly how the
alpha.c2.org anonymous remailer works, having never used
it; but it is something like this so I thought i'd use
it for an example anyhow.
Notice that the first block uses the [pgpns] tag so that PGP
envelope is not signed, but the pgp inside the pgp is signed, so
to authenticate to your friend that the message is indeed from
you. No [theend] is used because in this case we want the entire
rest of the text encrypted, so it is not necessary.
This is not a full description of how to use alpha.c2.org
anonymous remailer; you will have to be creative and figure out
how to apply these techniques yourself. (If anyone figures out a
good procedure for this and wants to write it up, step by step,
I'll include it in my docs).
A Few More Details
~~~~~~~~~~~~~~~~~~
Any text on the same line following a block tag or a block
terminal tag is ignored.
-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-10-
Anonymous Remailers
-------------------
I have been having some discussion with one of the users of
Yep about adding some support for automating posting messages
through an anonymous remailer (specifically anon.penet.fi --
send a blank message to help@anon.penet.fi if you want more
info about this service).
(see the end of the section on block processing for more
hints on how to use alpha.c2.org remailers)
We were brainstorming a scheme to do this (well, i was more
confused than anything), when it was realized that it turns
out to be as simple as this:
Set up the newsgroup you wish to regularly post annoymously
in the same as you would set up a "pseudo-newsgroup" with
Yarn. That is, run Yarn's NEWGROUP utility something like
this:
NEWGROUP rec.books.misc 7 30 rec.books.misc@anon.penet.fi
Notice you are setting up this newsgroup to keep messages
a default of 7 days, and a maximum of 30 days, and at the
end you are telling Yarn that all posts to this newsgroup
are to be E-MAILED to the anonymous remailer.
Now if you are familiar with this remailer service then
you will know (and if you aren't familiar with it you are
probobly confused by now) that you usually need to use a
password on your messages. This is done by adding a header
like this:
X-Anon-Password: your_password
Yep can detect that the message being written is addressed to
the anonymous re-mailer and add the password header line
automatically if you set up a custom header like this:
{ifto:anon.penet.fi}X-Anon-Password: password
There, with Yep and Yarn you now have pretty much automated
the task of coresponding in a newsgroup via this anonymous
remailer. This could be useful, for example, if you are
Salman Rushdie, hiding out from certain Iranians, but still
want to be active in rec.books.misc!
For a bit (but not much) more security Yep provides a way
to "encrypt" your password in your Yep.Cfg so someone
browsing the file won't be able to read it. See the
{YPDec:code} tag somewhere above.
Thanks to C.B. (now who could that be?!) for getting most
of this figured out.
-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-11-
Of Finding Problems -- Troubleshooting
--------------------------------------
Critical Errors
~~~~~~~~~~~~~~~
If there is any sort of critical error, Yep will create a
file called "yep.err" with some details of the problem
which you can email to me to report the bug.
Other Problems
~~~~~~~~~~~~~~
If you have having problems with a filter or condition,
or other Yep function, to test out your configuration
I suggest creating a test message and running YEP from
the command line on that message. This is the fastest
way to run Yep and try to find out what is going wrong.
The easiest way to create a test message is to go into
Yarn and reply to a message. Then when in your editor
save this reply to some text file to use for testing.
(Keep a backup of this text file because if Yep is
messing you up you will need to make more copies of
it as you continue testing. Make sure the test message
has a file extension of .msg or Yep will not interpret.
As a last resort send me your configuration file and
a test message (preferably zipped up), and an explanation
of what you are trying to do, and i'll try and see what's
going on for you.
-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-12-
History of Revision:
-------------------
Version 1.6 - Nov ??, 1996 (this is a beta document)
-----------
+ Definable filename extentions, so YEP can be used with other
mailers/newsreaders. See "Process=" in the YEP.CFG and the
"Yep But Not Yarn" section of chapter 2 above.
+ Yep now STOPS on some tag errors (mostly file importing)
and after printing an error message waits for you to press
a key to continue. No more too-fast-to-read errors messages!
+ New tag: {RNDC:string}. Random characters! See chapter 8
above under "Special Tags", and also "Special Precedence".
+ Major new feature: Block Processing. See section 9 above.
A few sample filters have been included for testing out
this feature, including: pigsay - simple pig latin filter,
rev-rexx - reverses each line of text, rep-rexx - replace
letters or paterns with other letters or paterns. These
are in the YX-*.ZIP archive included with the YEP archive.
+ Yep now searches your %HOME%\yarn\ directory for a yep.cfg file
FIRST. If none is found there, then the directory yep.exe is
executed from is searched (as earlier version do).
Easier for multi-user to have individual config files in their
home\yarn directories. (No changes necessary to your setup).
+ New tag: {RNDN:#:#}. Random number generator! See chapter 8
above under "Special Tags", and also "Special Precedence".
+ Certain tags now have "special precedence" and can be nested
in other tags (only one level deep). See the section entitled
"Special Precidence" (section 8) above.
+ New tag: {header:name}. This will print the value of certain
specified headers. For example {header:subject} will print
the value of the "Subject:" header. Headers supported are:
To, From, Subject, Date, Newsgroups, X-Newsgroups, References,
Reply-To, Sender. (this is intended for use with a possible
kludge support for the alpha.c2.org anonymous remailer)
+ New support to reflow quotes which would normally go beyond
the specified right margin. Still can be messy (as it's not FULL
reflow support, but only reflows individual lines), but better
yarn's usual (lack of) treatment. See the "RightMargin" and
"QuoteChar" in the yep.cfg. Note: a RightMargin="0" disables
this feature.
+ Along with the quote reflow support I've made made yep NOT
interpret any lines beginning with the specified quote character,
as it use to do on every single line before... This should speed
up processing of LONG quoted replies significantly.
+ New small "trouble shooting" section of this doc
+ more conditional tags IFCC, IFBCC, IFRT.
- the url grabber didn't recognize a tab as the end of an url.
- cleaned up (restructured) a few routines
- another minor extremely rare bug too complicated to explain.
- Completely revamped the way all the File I/O channels were
handled. This fixed an obscure bug that occured if you inserted
a file import tag AFTER entering the text editor. It also
increases memory use slightly, but should be more stable.
- Increased stack size, just for a little more elbow room
during file import recursions
- UrlLog="" in the Yep.cfg would crash YEP
- Uninitialised variable when exporting URLs caused instability.
Version 1.5 - March 4, 1996
-----------
+ New tag for automatically adding "Expires:" headers in case
you want to specify how long your message should live out in
cyberspace. See the {ExpD:#} tag in section 9 above.
+ A new feature: Automatic URL Logging. See the all new section 6
of this doc for details. No, not section 8, section 6!
+ new tag "Import Line Starting-With" {ImpLS:"string"::"filename"}
see details in section 3.
+ scary new uuencode tag! You can now uuencode a file into your
message with the ease of typing {uuen:filename}. As soon as you
exit your editor the file will be uuencoded like lightning...
right into your message; for those not partial to MIME.
+ Emacs header mode?? (see yep.cfg) [req. by huug@telebyte.nl]
+ The mysterious ImpLR (import line range) tag.
+ Added an {IfXN:string} conditional tag for testing the
X-Newsgroups: header. [req. of Cheryl Buzzell]
+ Moved the Phase of the Moon program into Yep so it can be called
with the tag {POM:#} where # is the number of decimal places.
+ Moved the "DateTime" utility into Yep so formatted date/time
strings can be added to SIG's or whatever, without shelling.
This subroutine can print other weird stuff like the percentage
of the day used up so far, and so on... see the docs somewhere.
+ Added the YPEnc word encryptor into the package. It can be used
to encrypt (sort of) passwords in the Yep.Cfg. See YPEnc.Doc.
+ Devoted a chapter of the doc to using Yep/Yarn and Anonymous
Remail services (anon.penet.fi, anyhow). See the table of
contents.
? Skipped version 1.4 for religious reasons.
- bug bug where most "if" tags didn't work correctly if you had
"cleanheader" turned on. Ouch. [Figured out by Han Willemsen
J.Willemsen@Inter.NL.net]
- some people were experiencing duplicate headers appearing when
re-editing messages. Not sure why, but think it's fixed anyhow!
[first reported by Jani Patanen (jpatanen@hit.fi)]
- Custom headers were being stripped of leading spaces, which was
not good for multi-line headers (where the lines after the first
were indented... fixed (hopefully not breaking anything else).
[alerted raised by Morten Frederiksen (mortenf@login.dknet.dk)]
Version 1.3 - February 13, 1996
-----------
+ new tag "Import Line Number" {ImpL:#:filename} - will import
a specified line number of a text file. See section 3.
+ added a few more meaningful, english, error messages. (-;
+ faster, faster, faster. Yep should be noticeably faster
(modified scanning routines), especially on long messages.
- a bug in the "IfFlag" logic found and fixed [thanks to
cherylb@tiac.net (Cheryl Buzzell) for help finding this one].
- the bug that almost killed me! Many thanks to the longsuffering
tsawchuc@kestrel.punk.net (Tim Sawchuck) who reported the
strange and mysterious "teh"::"the" substitution bug. After
many, many trials and tribulations that could fill a long
novel, suffice it to say-- it turned out to have nothing to
do with that substitution (the symptom just shows up for Tim
during it, but the bug (corruption) happens earlier), and this
bug is officially (i hope) squashed, thank God, it nearly killed
me. The problem, precisely, occurred if you used substitutions
*IN* a custom header *AND* the replacement text was longer
than the original text. I hope that clears it up for everyone!
- andrews@jolt.mpx.com.au (Andrew Shipton) finally noticed that
Yep wasn't allowing Yarn 'score' files to get passed through to
the editor. Doh! Fixed now, more or less! Sorry about that.
- better handling of {IfFlag:} and {SetFlag:} so that blank lines
are not left in a situation like this:
{ifflag:false}{ifng:yarn}This is the yarn mail list.
Previously if this "yarn" was not found in the newsgroups:
header then an awkward blank line would have been left behind.
No more. Should work much better with long lists of conditions
in SIGs or headers.
Version 1.2 - February 4, 1996
-----------
- very unfortunate bug that kept version 1.1 from running AT ALL
with the default yep.cfg due an error and bad parsing of the
[substitutions] section of yep.cfg. Fixed. Sorry! (If you
removed all blank lines from the yep.cfg it would work)
Version 1.1 - January 31, 1996
-----------
+ the old 255 character per line limit is now 50,000.
+ new yep.cfg directive: CleanHeader = "No"/"Yes" (see yep.cfg)
[thanks to suggestion by someone whom I lost the email of]
+ new yep.cfg directive: ShowDots = "Yes"/"No" (see yep.cfg)
+ $l (lower case L) in yep.cfg Editor= statement sets cursor
line number to the first line after the quotes in a reply.
[thanks to suggestion by lennart.carlson@mailbox.swipnet.se]
+ bizarre new experimental conditional tags: please see section
5 of this document above for details if interested.
+ custom header lines increased from 12 to 50
+ maximum substitutions raised from 25 to 100
+ new yep.cfg directive: CursorAdjust (see yep.cfg)
Version 1.0 - December 31, 1995
-----------
? Released. Sort of.
-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-13-
Credits:
-------
Yarn off-line news/mail reader of DOS and OS/2 (the reason we are gathered
here today, dearly beloved) is by Chin Huang. (http://www.vex.net/yarn)
Yes (Yarn Editor Shell) is by Per Goetterup and is a very good DOS program.
You can check it out as well at... http://www.vex.net/yarn
And lastly and leastly there's me: Tim Middleton (as544@torfree.net)
Well gee, I guess I'll join the party at http://www.vex.net/yarn too!
Sorry if this documentation is a bit crappy and not explained well. (-:
Just email me if you need help, or post to the Yarn mailing list.
-----------------------------------------------------------------
Yarn/2 Bells and Whistle's on the WWW
http://www.vex.net/~x/bells2.phtml
More good Yarn related Stuff!!!
-----------------------------------------------------------------